<!--

    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

-->

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
  <head>
    <title>org.netbeans.spi.editor.codegen</title>
  </head>
  <body>

  <p>
  The Code Generator SPI gives modules a chance to plug their own code generators
  into the popup that appears in the editor on the Insert Code action invocation.
  </p>


  <h3>Key parts of the SPI</h3>

  <p>
  The whole SPI is organized around the
  <code><a href="@org-netbeans-modules-editor-lib2@/org/netbeans/spi/editor/codegen/CodeGenerator.html">CodeGenerator</a></code>
  interface, which is the ultimate thing that modules need to implement in order to generate
  code snippets and insert them into a document on the Insert Code action invocation.
  The <code>CodeGenerator</code>s are created by
  <code><a href="@org-netbeans-modules-editor-lib2@/org/netbeans/spi/editor/codegen/CodeGenerator.Factory.html">CodeGenerator.Factory</a></code>
  instances.
  </p>

  <p>
  Instances of the
  <code><a href="@org-netbeans-modules-editor-lib2@/org/netbeans/spi/editor/codegen/CodeGeneratorContextProvider.html">CodeGeneratorContextProvider</a></code>
  interface serve for adding an additonal content to the context which is passed
  as a parameter to the
  <code><a href="@org-netbeans-modules-editor-lib2@/org/netbeans/spi/editor/codegen/CodeGenerator.Factory.html#create-org.openide.util.Lookup-">CodeGenerator.Factory.create</a></code>
  method.
  </p>
  
  
  <h3>CodeGenerator and CodeGeneratorContextProvider registration</h3>
  
  <p>
  The registration of <code>CodeGenerator</code>s has to be done through an
  instance of the <code>CodeGenerator.Factory</code> class. The factory should
  be registered in <code>MimeLookup</code> under the mime-type of documents, which
  the <code>CodeGenerator</code> should be used for, in the <code>CodeGenerators</code>
  folder. For example, if a module wants to provide <code>CodeGenerator</code>
  for <code>text/x-something</code> documents, it should implement its own
  <code>CodeGenerator.Factory</code> (e.g. <code>org.some.module.CGFactory</code>
  class) and register it in <code>MimeLookup</code> using its XML layer as it is
  shown on the example below.
  </p>
  
  <pre>
&lt;folder name="Editors"&gt;
  &lt;folder name="text"&gt;
    &lt;folder name="x-something"&gt;
      &lt;folder name="CodeGenerators"&gt;
        &lt;file name="org-some-module-CGFactory.instance" /&gt;
      &lt;/folder&gt;
    &lt;/folder&gt;
  &lt;/folder&gt;
&lt;/folder&gt;
  </pre>

  <p>
  The <code>CGFactory</code> class will simply return a new instance of
  the module's implementation of the <code>CodeGenerator</code> interface from its
  <code><a href="@org-netbeans-modules-editor-lib2@/org/netbeans/spi/editor/codegen/CodeGenerator.Factory.html#create-org.openide.util.Lookup-">create</a></code>
  method. The method can create and return multiple <code>CodeGenerator</code>s.
  </p>

  <p>
  The parameter of the <code>create</code> method provides by default access to
  the <code>JTextComponent</code>, which the generator is being created for. However,
  a group of factories could exist for a mime-type which require access to
  an additional data (e.g. some parser result, etc.) when creating their
  <code>CodeGenerator</code>s. To that purpose, an instance of 
  <code>CodeGeneratorContextProvider</code> interface could be created and registered
  in <code>MimeLookup</code> under the mime-type in the <code>CodeGeneratorContextProviders</code>
  folder. For example, if a module wants to provide an additional context for
  <code>text/x-something</code> <code>CodeGenerator.Factory</code> it should
  implement its own <code>CodeGeneratorContextProvider</code>
  (e.g. <code>org.some.module.CGContextProvider</code> class) and register it in
  <code>MimeLookup</code> using its XML layer as it is shown on the example below.
  </p>
  
  <pre>
&lt;folder name="Editors"&gt;
  &lt;folder name="text"&gt;
    &lt;folder name="x-something"&gt;
      &lt;folder name="CodeGeneratorContextProviders"&gt;
        &lt;file name="org-some-module-CGContextProvider.instance" /&gt;
      &lt;/folder&gt;
    &lt;/folder&gt;
  &lt;/folder&gt;
&lt;/folder&gt;
  </pre>

  <p>
  The <code>CGContextProvider</code> class in its
  <code><a href="@org-netbeans-modules-editor-lib2@/org/netbeans/spi/editor/codegen/CodeGeneratorContextProvider.html#runTaskWithinContext-org.openide.util.Lookup-org.netbeans.spi.editor.codegen.CodeGeneratorContextProvider.Task-">runTaskWithinContext</a></code>
  method creates the new context by merging the original context content
  with the additional data and runs the task obtained as the parameter with the newly
  created context. 
  </p>

  <h3><a name="usecases">Use cases</a></h3>

  <p style="color:red">TBD</p>

  </body>
</html>
